Mac Magazin/MacEasy 14

home *** CD-ROM | disk | FTP | other *** search

/ Mac Magazin/MacEasy 14 / Mac Magazin and MacEasy Magazine CD - Issue 14.iso / Wissenschaft & Technik / Tools Plus 2.6.1 Evaluation Kit / Tools Plus 2.6.1 / User Manual / 02-Installing Tools Plus < prev next >

Wrap

INI File | 1995-08-25 | 28KB | 595 lines

[Display using Monaco 9] 2 Installing Tools Plus ```````````````````````` Tools Plus Contents ``````````````````` This Evaluation Kit comes with several varieties of Tools Plus. The one you use depends upon the compiler you are using (Metrowerks or Symantec) and the language you are programming in (C/C++ or Pascal). Tools Plus software is made up of the following items: “ToolsPlus.Lib” Library containing all Tools Plus routines (CodeWarrior only) “ToolsPlus.Lib1” Library containing Tools Plus routines (1 of 3) (Symantec compilers only) “ToolsPlus.Lib2” Library containing Tools Plus routines (2 of 3) (Symantec compilers only) “ToolsPlus.Lib3” Library containing Tools Plus routines (3 of 3) (Symantec compilers only) “ToolsPlus.h” C header file for Tools Plus (C only) “ToolsPlus.c” Source code for routines that must be compiled with your application. When compiling for 680x0 processors, these routines will be compiled according to your project’s preferences for processor (680x0) and/or math co-processor optimization. When compiling for PowerPC, these routines are simply added to your project. (C only) “ToolsPlus.p” Pascal interface file for Tools Plus (Pascal only) “Palette WDEF” Optional resource file containing the WDEF resource (window definition) for floating palettes. Found in the “Optional Resources” folder. “Demos” Folder containing a demo application and its source code Tools Plus Segments in Your Application (for 680x0 only) ```````````````````````````````````````````````````````` The segments containing the Tools Plus libraries and the ToolsPlus.c or ToolsPlus.p file will be constantly accessed while your application is running. To reduce memory fragmentation, flag these segments as “Preload” and “Locked.” Warning: Do not unload the segments containing Tools Plus libraries. You can ensure that this doesn’t happen accidentally by flagging them as not “Purgeable.” ----------------------------------------------------------------------- Installing Tools Plus for THINK C ````````````````````````````````` Drag the ToolsPlus.Lib1, ToolsPlus.Lib2 and ToolsPlus.Lib3 libraries into the C Libraries folder, and ToolsPlus.h into the Mac #includes folder, or where ever you keep your other header files. You can drag the ToolsPlus.c file into your C Libraries folder, even though it is not a library. Keeping it with the ToolsPlus.Lib1, ToolsPlus.Lib2 and ToolsPlus.Lib3 libraries will help to remind you to include ToolsPlus.c in your project. Adding Tools Plus to a THINK C Project `````````````````````````````````````` To add Tools Plus to a THINK C project, first open your project, then use the Source menu’s Add… command to add the file ToolsPlus.Lib1, ToolsPlus.Lib2, ToolsPlus.Lib3, and ToolsPlus.c. Even though Tools Plus libraries can be located anywhere in your project, placing them at the top will organize it a little better. Drag each of the libraries (ToolsPlus.Lib1, ToolsPlus.Lib2, and ToolsPlus.Lib3) into their own segment. For convenience, drag ToolsPlus.c to the segment containing the last Tools Plus library. Note that all projects using Tools Plus must also include Symantec’s MacTraps library. ----------------------------------------------------------------------- Installing Tools Plus for THINK Pascal `````````````````````````````````````` Drag the ToolsPlus.Lib1, ToolsPlus.Lib2, and ToolsPlus.Lib3 libraries into the Libraries folder, and ToolsPlus.p into the Interface folder, or where ever you keep your other libraries and interfaces. Adding Tools Plus to a THINK Pascal Project ``````````````````````````````````````````` To add Tools Plus to a THINK Pascal project, first open your project, then use the Project menu’s Add File command to add the files ToolsPlus.Lib1, ToolsPlus.Lib2, ToolsPlus.Lib3, and ToolsPlus.p to your project. Build Order… Though libraries can be located anywhere in your build order, placing them near the top (early in the compiling order) will organize your project a little better. The ToolsPlus.p interface has to be compiled BEFORE your source code makes reference to it. Placing it immediately below the libraries is a good, safe place By Segment… Drag each of the Tools Plus libraries into their own segment. For convenience, drag the ToolsPlus.p interface file into the segment containing the last Tools Plus library. After Compiling ``````````````` So far, you’ve told THINK Pascal what files to use and the order in which they should be compiled. When you compile your project the first time, THINK Pascal loads the specified libraries and integrates them into your project file, and it compiles source files (including ToolsPlus.p) and integrates them in your project file. After your first compile, you’ll notice that THINK Pascal automatically added several items to your project file: «ToolsPlus.Lib1:1» «ToolsPlus.Lib2:1» «ToolsPlus.Lib3:1» «%_MethTables» «%_SelProcs» «%_Profiler» The «ToolsPlus.Lib1:1», «ToolsPlus.Lib2:1» and «ToolsPlus.Lib3:1» items contain the object code from the Tools Plus libraries, while «%_MethTables», «%_SelProcs» and «%_Profiler» items are part of THINK Pascal’s overhead (consult your THINK Pascal User Manual for details). Drag «ToolsPlus.Lib1:1» into the same segment as ToolsPlus.Lib1, «ToolsPlus.Lib2:1» into the same segment as ToolsPlus.Lib2, etc. Drag «%_MethTables», «%_SelProcs» and «%_Profiler» to any segment that won’t be unloaded while your application is running, such as the one containing the Runtime.Lib library. Even though the project window indicates that Segment 1 exceeds the 32k limit imposed on segments, the project will compile and run. When you build your application, the smart linker will strip away unneeded code and significantly reduce the size of this segment. Note: Tools Plus does not have a dependency on the Runtime.Lib library. Unless your application needs routines that are found only in the full Runtime.Lib library, you can use the smaller µRuntime.Lib library instead ----------------------------------------------------------------------- Installing Tools Plus for CodeWarrior C (68K) ````````````````````````````````````````````` CodeWarrior is very flexible as to where it looks for files, so you can put Tools Plus libraries and support files just about anywhere on your disk as long as you define an access path to those files in your project’s preferences. A good idea is to create a folder named “Tools Plus (68K) C/C++” (without the version number) in a convenient place on your hard disk. When you create a new project, set an access path to this folder. Your projects will automatically use newer versions of Tools Plus as long as you place the new files in this folder. Drag the ToolsPlus.Lib, ToolsPlus.c and ToolsPlus.h files into your Tools Plus folder. Adding Tools Plus to a CodeWarrior C (68K) Project `````````````````````````````````````````````````` To add Tools Plus to a CodeWarrior C project, first open your project, then use the Project menu’s Add Files… command to add the files ToolsPlus.Lib and ToolsPlus.c into your project. All projects using Tools Plus need to include the following Metrowerks libraries: MacOS.Lib ANSI (2i) C.68K.Lib (or equivalent) PASCAL.68K.Lib (or equivalent) Note that the PASCAL.68K.Lib is a component of your CodeWarrior Pascal compiler. In CodeWarrior 6, the file is named “P/RT.68K.lib”. Even though Tools Plus libraries can be located anywhere in your project, placing them at the top will organize it a little better. Drag the ToolsPlus.Lib library into its own segment. For convenience, drag the ToolsPlus.c file to the same segment containing the ToolsPlus.Lib library. Warning: Applications using Tools Plus must use 2-byte integers. Make sure your “4-byte ints” option is turned off in to your project’s preferences (processor options). If your application needs 4-byte integers, redeclare integers to be longs throughout your code. ----------------------------------------------------------------------- Installing Tools Plus for CodeWarrior Pascal (68K) `````````````````````````````````````````````````` CodeWarrior is very flexible as to where it looks for files, so you can put Tools Plus libraries and support files just about anywhere on your disk as long as you define an access path to those files in your project’s preferences. A good idea is to create a folder named “Tools Plus (68K) Pascal” (without the version number) in a convenient place on your hard disk. When you create a new project, set an access path to this folder. Your projects will automatically use newer versions of Tools Plus as long as you place the new files in this folder. Drag the following files into your Tools Plus folder: ToolsPlus.Lib and ToolsPlus.p. Adding Tools Plus to a CodeWarrior Pascal (68K) Project ``````````````````````````````````````````````````````` To add Tools Plus to a CodeWarrior Pascal project, first open your project, then use the Project menu’s Add Files… command to add the files ToolsPlus.Lib and ToolsPlus.p to your project. All projects using Tools Plus need to include the following Metrowerks libraries: In CodeWarrior 7: MacOS.lib MacIntf(UPI).68K.lib (or equivalent) ANSI (2i) C.68K.Lib (or equivalent) PASCAL.68K.Lib In CodeWarrior 6: Pascal/MacOS.Lib MacIntf(UPI).68K.lib (or equivalent) P/ANSI.68K.Lib (or equivalent) P/RT.68K.lib Even though Tools Plus libraries can be located anywhere in your project, placing them at the top will organize it a little better. Drag the ToolsPlus.Lib library into its own segment. For convenience, drag the ToolsPlus.p file to the same segment containing the ToolsPlus.Lib library. ----------------------------------------------------------------------- Installing Tools Plus for CodeWarrior C (PPC) ````````````````````````````````````````````` CodeWarrior is very flexible as to where it looks for files, so you can put Tools Plus libraries and support files just about anywhere on your disk as long as you define an access path to those files in your project’s preferences. A good idea is to create a folder named “Tools Plus (PPC) C/C++” (without the version number) in a convenient place on your hard disk. When you create a new project, set an access path to this folder. Your projects will automatically use newer versions of Tools Plus as long as you place the new files in this folder. Drag the ToolsPlus.Lib, ToolsPlus.c and ToolsPlus.h files into your Tools Plus folder. Adding Tools Plus to a CodeWarrior C (PPC) Project `````````````````````````````````````````````````` To add Tools Plus to a CodeWarrior C project, first open your project, then use the Project menu’s Add Files… command to add the files ToolsPlus.Lib and ToolsPlus.c into your project. All projects using Tools Plus need to include the following Metrowerks libraries: MWCRuntime.Lib InterfaceLib ANSI C.PPC.Lib (or equivalent) PASCAL.PPC.lib (or equivalent) Note that the “PASCAL.PPC.lib” library is a component of your CodeWarrior Pascal compiler. In CodeWarrior 6 it is named “P/Rt.PPC.lib”. Even though the Tools Plus library can be located anywhere in your project, placing it at the top will organize the project a little better. Add ToolsPlus.Lib and ToolsPlus.c to your project. For convenience, you may want to keep these two files in the same group. ----------------------------------------------------------------------- Installing Tools Plus for CodeWarrior Pascal (PPC) `````````````````````````````````````````````````` CodeWarrior is very flexible as to where it looks for files, so you can put Tools Plus libraries and support files just about anywhere on your disk as long as you define an access path to those files in your project’s preferences. A good idea is to create a folder named “Tools Plus (PPC) Pascal” (without the version number) in a convenient place on your hard disk. When you create a new project, set an access path to this folder. Your projects will automatically use newer versions of Tools Plus as long as you place the new files in this folder. Drag the following files into your Tools Plus folder: ToolsPlus.Lib and ToolsPlus.p. Adding Tools Plus to a CodeWarrior Pascal (PPC) Project ``````````````````````````````````````````````````````` To add Tools Plus to a CodeWarrior Pascal project, first open your project, then use the Project menu’s Add Files… command to add the files ToolsPlus.Lib and ToolsPlus.p to your project. All projects using Tools Plus need to include the following Metrowerks libraries: In CodeWarrior 7: MWCRuntime.Lib InterfaceLib MacIntf(UPI).PPC.Lib (or equivalent) ANSI C.PPC.lib (or equivalent) PASCAL.PPC.lib In CodeWarrior 6: MWPRuntime.Lib InterfaceLib MacIntf(UPI).PPC.Lib (or equivalent) P/ANSI.PPC.lib (or equivalent) P/Rt.PPC.lib Even though the Tools Plus library can be located anywhere in your project, placing it at the top will organize your project a little better. Add ToolsPlus.Lib and ToolsPlus.p to your project. For convenience, you may want to keep these two files in the same group. ======================================================================= Compiling the THINK C Demo Application `````````````````````````````````````` The easiest way to compile the THINK C demo application included with Tools Plus is to have the following files in the same folder: Demo.π Demo.π.rsrc Demo.c ToolsPlus.Lib1 ToolsPlus.Lib2 ToolsPlus.Lib3 ToolsPlus.h ToolsPlus.c PascalStrHandles.c Double-click the Demo.π project file to launch THINK C, then run your project. Your project file keeps track of each file’s location as you add it to your project, so you may want to create a new project file after you have put all the Tools Plus libraries and related files in their permanent folders. Create a new (empty) project named “Demo.π” in the same folder as “Demo.π.rsrc” and “PascalStrHandles.c”. Add the following files to your new project: Segment 1: MacTraps MacTraps2 Segment 2: ANSI Segment 3: ToolsPlus.Lib1 Segment 4: ToolsPlus.Lib2 Segment 5: ToolsPlus.Lib3 ToolsPlus.c Segment 6: Demo.c You can now build your project and run your application. Note: Make sure you allocate sufficient memory to the debugger if you are going to run the Tools Plus demo application with the debugger on. The Tools Plus demo was written as one large source file, making it easier to compile and study, but making it hungry for debugger memory. Allocate at least 500K to the debugger. If you don’t have enough memory, turn the debugger off (Project menu, deselect “Use Debugger”) when running the demo. Your applications will likely be written in a more intelligent fashion, abandoning one large source file in favor of several smaller ones. IMPORTANT! Errors when compiling the Demo… `````````````````````````````````````````` At the time of this writing, Water’s Edge Software has made every effort to ensure that our demo application will compile successfully the first time. Unfortunately, Symantec C/C++ compilers have undergone a series of revisions and some inconsistencies have arisen between compiler versions. Fortunately, these differences are simple to resolve. If your compiler gives you an error that states “argument to function ‘x’ does not match prototype,” it indicates that Symantec has made a minor revision to that function’s prototype (in the error message, ‘x’ will be replaced by the function’s name). To correct this error, inspect the offending line in the source file, which is likely a line like: PenPat(&gray); and revise it to match the prototype in the related header file. In the example above, the correction is as simple as changing the line to: PenPat(gray); /* Remove ampersand (&) from the variable */ To date, all inconsistencies have been of this nature. We are sorry for the inconvenience these issues may cause you, and would like to offer our assistance if you have problems getting the demo compiled. See the “Technical Support” chapter for information on how to contact Water’s Edge Software for assistance. ----------------------------------------------------------------------- Compiling the THINK Pascal Demo Application ``````````````````````````````````````````` The easiest way to compile the THINK Pascal demo application included with Tools Plus is to have the following files in the same folder: Demo.π Demo.π.rsrc Demo.p ToolsPlus.Lib1 ToolsPlus.Lib2 ToolsPlus.Lib3 ToolsPlus.p Double-click the Demo.π project file to launch THINK Pascal, then run your project. Your project file keeps track of each file’s location as you add it to your project, so you may want to create a new project file after you have put all the Tools Plus libraries and related files in their permanent folders. Create a new project named “Demo.π” in the same folder as “Demo.π.rsrc”. Add the following files to your new project: Segment 1: Runtime.Lib Interface.Lib Segment 2: ToolsPlus.Lib1 Segment 3: ToolsPlus.Lib2 Segment 4: ToolsPlus.Lib3 ToolsPlus.p Segment 5: Sound.p Demo.p You can now build your project. After the initial compile, you will notice THINK Pascal created some additional entries in your project file: «ToolsPlus.Lib1:1» «ToolsPlus.Lib2:1» «ToolsPlus.Lib3:1» «%_MethTables» «%_SelProcs» «%_Profiler» The «ToolsPlus.Lib1:1», «ToolsPlus.Lib2:1» and «ToolsPlus.Lib3:1» items contain the object code from the Tools Plus libraries, while «%_MethTables», «%_SelProcs» and «%_Profiler» items are part of THINK Pascal’s overhead (consult your THINK Pascal User Manual for details). Drag «ToolsPlus.Lib1:1» into the same segment as ToolsPlus.Lib1, «ToolsPlus.Lib2:1» into the same segment as ToolsPlus.Lib2, and «ToolsPlus.Lib3:1» into the same segment as ToolsPlus.Lib3. Drag «%_MethTables», «%_SelProcs» and «%_Profiler» to any segment that won’t be unloaded while your application is running, such as the one containing the Runtime.Lib library. Even though the project window indicates that Segment 1 exceeds the 32k limit imposed on segments, the project will compile and run. When you build your application, the smart linker will strip away unneeded code and significantly reduce the size of this segment. ----------------------------------------------------------------------- Compiling the CodeWarrior C (68K) Demo Application `````````````````````````````````````````````````` The easiest way to compile the CodeWarrior C demo application included with Tools Plus is to have the following files in the same folder: Demo.µ Demo.π.rsrc Demo.c ToolsPlus.Lib ToolsPlus.h ToolsPlus.c PascalStrHandles.c Double-click the Demo.µ project file to launch CodeWarrior C/C++, then run your project. If you are creating a new project (instead of using the one included as part of Tools Plus), you first need to install Tools Plus in your project file as described earlier in this chapter. Copy the files “Demo.µ”, “Demo.π.rsrc” and “PascalStrHandles.c” to the folder containing your project. Add the following files to your new project: Segment 1: MacOS.Lib ANSI (2i) C.68K.Lib (or equivalent) PASCAL.68K.Lib (or equivalent) Segment 2: ToolsPlus.Lib ToolsPlus.c Segment 3: Demo.π.rsrc Demo.c (Note that the PASCAL.68K.Lib is a component of your CodeWarrior Pascal compiler. In CodeWarrior 6, the file is named “P/RT.68K.lib”.) You can now build your project and run your application. ----------------------------------------------------------------------- Compiling the CodeWarrior Pascal (68K) Demo Application ``````````````````````````````````````````````````````` The easiest way to compile the CodeWarrior Pascal demo application included with Tools Plus is to have the following files in the same folder: Demo.µ Demo.π.rsrc Demo.p ToolsPlus.Lib ToolsPlus.p Double-click the Demo.µ project file to launch CodeWarrior Pascal, then run your project. If you are creating a new project (instead of using the one included as part of Tools Plus), you first need to install Tools Plus in your project file as described earlier in this chapter. Copy the files “Demo.µ” and “Demo.π.rsrc” to the folder containing your project. Add the following files to your new project: In CodeWarrior 7: Segment 1: MacOS.lib PASCAL.68K.Lib MacIntf(UPI).68K.lib (or equivalent interface) ANSI (2i) C.68K.Lib (or equivalent) Segment 2: ToolsPlus.Lib ToolsPlus.p Segment 3: Demo.π.rsrc Demo.p In CodeWarrior 6: Segment 1: Pascal/MacOS.Lib P/RT.68K.lib MacIntf(UPI).68K.lib (or equivalent interface) P/ANSI.68K.Lib (or equivalent) Segment 2: ToolsPlus.Lib ToolsPlus.p Segment 3: Demo.π.rsrc Demo.p You can now build your project and run your application. ----------------------------------------------------------------------- Compiling the CodeWarrior C (PPC) Demo Application `````````````````````````````````````````````````` The easiest way to compile the CodeWarrior C demo application included with Tools Plus is to have the following files in the same folder: Demo.µ Demo.π.rsrc Demo.c ToolsPlus.Lib ToolsPlus.h ToolsPlus.c PascalStrHandles.c Double-click the Demo.µ project file to launch CodeWarrior C/C++, then run your project. If you are creating a new project (instead of using the one included as part of Tools Plus), you first need to install Tools Plus in your project file as described earlier in this chapter. Copy the files “Demo.µ”, “Demo.π.rsrc” and “PascalStrHandles.c” to the folder containing your project. Add the following files to your new project: Group 1: MWCRuntime.Lib InterfaceLib ANSI C.PPC.Lib (or equivalent) PASCAL.PPC.lib (or equivalent) Group 2: ToolsPlus.Lib ToolsPlus.c Group 3: Demo.π.rsrc Demo.c (Note that the “PASCAL.PPC.lib” library is a component of your CodeWarrior Pascal compiler. In CodeWarrior 6 it is named “P/Rt.PPC.lib”.) You can now build your project and run your application. ----------------------------------------------------------------------- Compiling the CodeWarrior Pascal (PPC) Demo Application ``````````````````````````````````````````````````````` The easiest way to compile the CodeWarrior Pascal demo application included with Tools Plus is to have the following files in the same folder: Demo.µ Demo.π.rsrc Demo.p ToolsPlus.Lib ToolsPlus.p Double-click the Demo.µ project file to launch CodeWarrior Pascal, then run your project. If you are creating a new project (instead of using the one included as part of Tools Plus), you first need to install Tools Plus in your project file as described earlier in this chapter. Copy the files “Demo.µ” and “Demo.π.rsrc” to the folder containing your project. Add the following files to your new project: In CodeWarrior 7: Group 1: MWCRuntime.Lib InterfaceLib MacIntf(UPI).PPC.Lib (or equivalent interface) ANSI C.PPC.lib (or equivalent) PASCAL.PPC.lib Group 2: ToolsPlus.Lib ToolsPlus.p Group 3: Demo.π.rsrc Demo.p In CodeWarrior 6: Group 1: MWPRuntime.Lib InterfaceLib MacIntf(UPI).PPC.Lib (or equivalent interface) P/ANSI.PPC.lib (or equivalent) P/Rt.PPC.lib Group 2: ToolsPlus.Lib ToolsPlus.p Group 3: Demo.π.rsrc Demo.p You can now build your project and run your application. ----------------------------------------------------------------------- Errors when compiling the CodeWarrior demos (or applications): `````````````````````````````````````````````````````````````` At the time of this writing, Water’s Edge Software has made every effort to ensure that our demo application will compile successfully the first time. Unfortunately, Apple (who produces the C/C++ headers and Pascal interfaces into the Macintosh’s toolbox) and Metrowerks development environments are undergoing a series of revisions. As a result, some inconsistencies may arise between compiler versions. Fortunately, these differences are simple to resolve. Access Paths ```````````` When using Tools Plus for CodeWarrior C/C++ (680x0 or PowerMac), a Pascal runtime library is required. You may have to change the Access Path (in your project’s preferences) to locate the required file. This applies to the demo application as well as the project in the “starter files” folder. File Names `````````` Metrowerks occasionally changes the names of their libraries. If your demo project (or starter project) can’t locate a file, remove the problem file from your project then add the equivalent, correctly named file. An Access Path to the correctly named file will be created automatically if it is required. Routine Names ````````````` At the time of this writing, Apple was still revising the routine and constants names in their universal interfaces. Your compiler or linker will find these inconsistencies and bring them to your attention. If the application you are compiling uses constants that have been renamed in the new universal interfaces, you can resolve this in one of two ways: 1) Go through your source code and replace all occurrences of the old constant with the new constant name 2) Define the old constant in a C/C++ header or Pascal interface file If the application you are compiling uses routine names that have been renamed in the new universal interfaces, the linker will discover this and report it to you. You can resolve this in one of two ways: 1) Go through your source code and replace all occurrences of the old routine name with the new routine name 2) “Map” the old routine name to the new routine name used in the newest universal interfaces. If a Tools Plus library refers to a routine that has been renamed in the new universal interfaces, define the old routine (so that the Tools Plus library can find it), and have the old routine call the new routine. The following example shows you how to do this: function GetCtlValue (theControl: ControlRef): INTEGER; begin GetCtlValue := GetControlValue(theControl) end; The above example illustrates how the old GetCtlValue routine is mapped to the new GetControlValue routine found in the universal interfaces. Make sure that you defile the old routine with identical parameter names and types as the new routine.